package org.newlucene.core.index;

import java.io.IOException;

/** TermDocs provides an interface for enumerating &lt;document, frequency&gt;
  pairs for a term.  <p> The document portion names each document containing
  the term.  Documents are indicated by number.  The frequency portion gives
  the number of times the term occurred in each document.  <p> The pairs are
  ordered by document number.
  */

public interface TermPostings 
{
	/** Sets this to the data for a term.
	 * The enumeration is reset to the start of the data for this term.
	 */
	public void seek(Term term) throws IOException;

	/** Returns the current document number.  <p> This is invalid until {@link
      #nextDoc()} is called for the first time.*/
	public int doc();

	/** Returns the frequency of the term within the current document.  <p> This
    	is invalid until {@link #nextDoc()} is called for the first time.*/
	public int freq();

	/** Moves to the next pair in the enumeration.  <p> Returns true iff there is
    	such a next pair in the enumeration. */
	public boolean nextDoc() throws IOException;

	/** Skips entries to the first beyond the current whose document number is
	 * greater than or equal to <i>target</i>. <p>Returns true iff there is such
	 * an entry.  <p>Behaves as if written: <pre>
	 * boolean skipTo(int target) {
	 *     do {
	 *       if (!next())
	 * 	     return false;
	 *     } while (target > doc());
	 *     return true;
	 *   }
	 * </pre>
	 * Some implementations are considerably more efficient than that.
	 */
	public boolean skipTo(int target) throws IOException;

	/** Returns next position in the current document.  It is an error to call
  	this more than {@link #freq()} times
  	without calling {@link #nextDoc()}<p> This is
  	invalid until {@link #nextDoc()} is called for
  	the first time.*/
	public int nextPosition() throws IOException;

	public int position();
  
	/** Frees associated resources. */
	public void close() throws IOException;
}